REST API

The REST API URI takes on the following forms:

https://rest.interfax.net/{resource}[/{operation}]

where:

• {resource} is the name of the resource being operated on, such as inbound/fax or outbound/batch.

• [operation] is an operation on the resource, such as mark or cancel.

• Optional items are enclosed in square braces and unbolded.

The URL may be followed by the query parameters, which take the form argument=value, where the arguments and values must be url-encoded. Multiple parameters are separated by an ampersand (&). The following example shows the URL for sending a fax to a certain number and forcing its paper size to “Letter” (shown here before url-encoding for readability):

https://rest.interfax.net/outbound/fax?faxNumber=+12125874586&pageSize=Letter

The API documentation for each operation provides its URL and lists all of the mandatory and optional parameters, in addition to describing the response structure, return headers, etc.

The service uses HTTP Basic authentication.

With HTTP Basic authentication, the username and password are submitted in a header within each HTTP call, as demonstrated in the example below. There is no server-side retention of an authenticated session, which means that authentication must be repeated with every call.

Tip: To ensure compatibility with all clients, please capitalize the word “Basic.”

GET /current/outbound/fax/865225412/meta HTTP/1.1
Host: rest.interfax.net
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

The formula for creating the authorization string is:

base64_encode($interfax_username . ":" . $interfax_password)

That is, concatenating the InterFAX username, a colon (:), and the InterFAX password, then base64-encoding the concatenated string.

Use of the API is always through an existing InterFAX “Primary” user (generally, any first user in an account is a primary user; subsequent users are normally opened as “Normal” users, but not necessarily) . There is no special API user required.

Attempting API operations, which require authentication, without performing authentication will return an HTTP error 401 (UNAUTHORIZED). For example, the unauthenticated call:

GET /current/outbound/fax/865225412/meta HTTP/1.1
Host: rest.interfax.net

will return the following HTTP headers:

HTTP/1.1 401 Authorization Required
WWW-Authenticate: Basic realm="Secure Area"

Help Tools

Helper operations

Endpoint	Description
https://rest.interfax.net/tests/date	Returns a provided date/time in local time, GMT, and xxx. Call like this: https://rest.interfax.net/tests/date?d=2011-12-16
https://rest.interfax.net/tests/error	Returns a provided error code as it would be returned by the API, for example try https://rest.interfax.net/tests/error?applicationStatus=300
https://rest.interfax.net/tests/errorcodes	Returns a list of all possible error codes.

Testers

Endpoint	Description
Outbound	https://rest.interfax.net/outbound/test
Inbound	https://rest.interfax.net/inbound/test
Account (to retrieve faxing credits)	https://rest.interfax.net/accounts/test

See System limitations for more information.

Fax Numbers

The safest, least ambiguous way to supply a fax number to the InterFAX API is the following:

+(country code)(area code)(fax number), for example: +12129874563

or

00(country code)(area code)(fax number), for example: 0012129874563

which consists of the following parts:

• A + symbol or the numbers 00

• The international country calling code.

• The area code with no local access prefix (except for Italy, where the local access prefix is required; e.g. Rome is 06)

• The fax number

Date-Times

Date-times are expected to be ISO 8601-compliant. Generally speaking, a date-time should look like this:

(date as YYYY-MM-DD)T(time)(GMT offset), for example: 2001-12-31T21:34+02:00

which is made up of the following parts:

• A date part, like 2005-12-31

• The letter T as a separator

• A time part, like 21:34

• A GMT time zone offset, like +02:00 or -08:00, specifying in which time zone the time part above is provided. In the absence of a time zone offset, or if the offset is 00:00 the time part provided will be assumed to be given in GMT.

Tip: Please remember to urlEncode the datetime value in the URL.

Booleans

Must be true or TRUE or false or FALSE (i.e., not numbers). If absent, a default of false is assumed.

See Supported file types for more information.

Request Elements

REST requests generally contain the following elements, some of which may be omitted for certain calls:

• URL

• HTTP request type (POST, GET, etc.)

• HTTP headers

• HTTP content

Their application to the InterFAX REST API is detailed below.

URL

Operation properties are submitted as key/value pairs in the command line. Keys are documented for each operation documented here. For example, to call POST /outbound/fax with all its properties populated, place an HTTP POST call like this (for reading convenience the query string has not been url-encoded):

https://rest.interfax.net/outbound/faxes?destination=+12154785412

Note that the query string in the URL above needs to be url-encoded to avoid prohibited characters (such as spaces). Once encoded it will look like this:

https://rest.interfax.net/outbound/faxes?destination=%2B12154785412

HTTP request types

HTTP calls may be of type HTTP GET, HTTP POST, or HTTP DELETE, depending on the specific operation being called. This reference describes which call type each operation supports.

HTTP headers

Some operations may require content to reside within the HTTP headers. This is the case for authentication, for example, where a correctly-populated Authorization header must be present.

HTTP content

Some operations may require content to reside within the HTTP call itself. For example, sending a fax requires the document you wish to fax to be placed in an HTTP POST call as MIME, and certain headers to be present in the call. For example:

POST /outbound/faxes?destination=+12125554584 HTTP/1.1
Host: rest.interfax.net
Content-Length: 1352
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: multipart/form-data; boundary=--------------------------+-7d03135102b8

-----------------------------7d03135102b8
Content-Disposition: form-data; name="file"; filename="C:\whatever\fax.txt"
Content-Type: text/plain

Hello there

Forcing a response format

By default, the REST response format is JSON, however, additional formats are available. The way to force a certain response format is by setting an Accept HTTP header in the request, like:

GET /outbound/faxes/85456521
Host: rest.interfax.net
Accept: application/xml

GZip Support

Content-Encoding: gzip

HTTP headers

A response code giving an initial indication of success or failure of an API call will be provided in the headers. For example, attempting to retrieve fax status information with incorrect InterFAX credentials will return an HTTP status code of 401 UNAUTHORIZED.

Upon successful creation of a new resource with a POST method, an HTTP “Location:” header will provide the URI of the newly-created resource. For example, when sending a fax with the POST /outbound/faxes operation, a successful response will return the location where the status of the fax can be queried, like

Location: https://rest.interfax.net/outbound/faxes/9658521.

HTTP content

Response content may occasionally be empty, with the required information being relayed by the HTTP response code (200, 404, etc.) and, optionally, the “Location:” header.

When the content area isn’t empty, its format will vary depending on the requested response format – JSON (Default), XML, or HTML. It will generally be structured as to show:

Upon success

Operation-dependent content, e.g. fax meta data

Optional MIME content, e.g. the TIFF image of a fax

Upon error

A structure providing the InterFAX response code, for example:

{
    "code":-113,
    "message":"Do we need this",
    "more_info":"List name [MyList2] does not exist"
}

A helper method that shows all possible REST response codes status is available here.

HTTP content formats

JSON (Default)

By default, REST requests will receive a JSON-structured response. For example, a response from operation GET /outbound/faxes/{id} will return the following:

{
    "id"     : 987654321,
    "basic"  :
    {
       "parentID"     : 876543210,
       "status"       : -3,
       "duration"     : 55
    }
}

Not defining a response type in the URL is equivalent to setting the “Accept:” header to “application/json”.

XML

To force the API to return a response as XML, set the “Accept:” header to “text/xml”. An XML response will be structured as:

       876543210
       -3
       55

Custom Headers

X-Elapsed-Time shows the time in milliseconds that it took to process the returned API call.